…ypass, leak, and lock

Code review of the initial dial-time guard surfaced several defects in how
the guard was attached to the dispatching *fasthttp.Client. Re-work the
attachment to use fasthttp's ConfigureClient hook, which runs once per
HostClient at creation, and address the findings:

- DialTimeout bypass (SSRF): fasthttp's callDialFunc prefers a client's
  DialTimeout over Dial, so guarding only Dial left DialTimeout-configured
  clients completely unvalidated. installHostClientGuard now wraps both
  DialTimeout (preserving its per-request timeout) and Dial.
- Timing: installing at HostClient creation (ConfigureClient) means the
  guard is present before the first dial to each host, instead of mutating
  Client.Dial after HostClients may already have been cached with the old
  dialer. The default client (init) and WithClient clients (before use) are
  fully guarded.
- Memory/resource leak: the previous global map keyed by *fasthttp.Client
  pinned every client (and its connection pool) forever. Guarding is now
  idempotent by identity (a stable package-level ConfigureClient hook), so
  the common case retains no client reference; only clients that already
  carry their own ConfigureClient use a sync.Map, composed once.
- Hot-path lock: dropped the process-global mutex acquired on every proxy
  request in favor of the lock-free identity check.

Refactor the dialer into a shared guardedDial core with DialFunc and
DialFuncWithTimeout variants. Add regression tests: a custom client that
sets DialTimeout is now blocked under DNS-rebinding, plus unit coverage for
ConfigureClient composition/idempotency and DialTimeout guarding.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FSa22vkkDLDTZctuKkmZ1A

Code review of the ConfigureClient-based guard found three defects:

- Compose order (SSRF re-open): the composed hook ran installHostClientGuard
  before the user's existing ConfigureClient, so a user hook that sets
  hc.Dial/hc.DialTimeout (the idiomatic reason to use ConfigureClient)
  overwrote the guard. Run the user's hook first, then install the guard, so
  it wraps whatever dialer the user finally sets.
- TOCTOU / data race: guarding published a "handled" flag before the guard
  field was written, letting a concurrent caller dispatch through a
  still-unguarded client; the field write was also unsynchronized. Serialize
  the whole read-modify-write under a mutex so the guard is installed before
  any other guarder observes the client.
- Hot-path cost: only guard the per-call variadic client on dispatch; the
  global/default client is guarded at registration, so the common no-variadic
  request path no longer touches the guard lock.

Tests: strengthen the compose test so it fails on the wrong order (the user
hook now installs its own hc.Dial and the guard must still block loopback and
delegate an allowed IP); add a concurrency test (race-detector regression
guard for the mutex); add a positive-path test that a validated hostname
resolves and dials through to the exact IP; add a DoRedirects rebinding case;
and key the fake resolver on the query name so a stray lookup cannot mask a
broken dial-time guard.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FSa22vkkDLDTZctuKkmZ1A

Follow-up review hardening:

- The fake resolver now counts A queries and returns the counter; the
  rebinding test asserts >= 2 lookups, proving the block happens at dial time
  (a second, rebound lookup) rather than up front — so a broken dial-time
  guard masked by an up-front block can no longer pass silently.
- Make the guard docs precise: clients with a nil ConfigureClient (the common
  case) are matched by identity and never retained; only a client carrying
  its own ConfigureClient is stored (one bounded entry per distinct client),
  with guidance to reuse such clients or register them via WithClient. Note
  that the per-request guardMu on a fixed variadic client is a deliberate
  correctness-over-throughput choice.

No behavior change; verified with go test -race.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FSa22vkkDLDTZctuKkmZ1A

Defense-in-depth from the final review pass. isBlockedIP already caught the
IPv4-mapped form (::ffff:a.b.c.d, which net.IP.To4 surfaces) but not the
IPv4-compatible (::a.b.c.d) or NAT64 well-known-prefix (64:ff9b::a.b.c.d)
forms, so a literal like ::127.0.0.1 or 64:ff9b::a9fe:a9fe (the metadata
address) resolved to false. Some stacks route these to the embedded IPv4, so
unwrap them and apply the same blocklist to the embedded address. Public
embedded addresses stay allowed. Table test extended with mapped, compatible,
and NAT64 cases (private blocked, public allowed).

Also correct the DomainForward doc: it validates (and resolves) the addr at
construction, which — unlike Balancer, which defers DNS — panics at startup on
an unresolvable addr. The previous "matches the Balancer contract" wording was
imprecise.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FSa22vkkDLDTZctuKkmZ1A

… race)

The macOS -race CI caught a data race: the rebinding test swaps the
process-global net.DefaultResolver, while a leaked fasthttp dial goroutine
from Test_Proxy_DoDeadline_PastDeadline reads it via net.Dialer.DialContext
(reached through the guard's delegate path now that the default client is
guarded). Mutating the stdlib global is inherently racy with background DNS
lookups anywhere in the test binary.

Add an atomic dnsResolver seam in the proxy package (defaults to
net.DefaultResolver) used by validateHostForSSRF and resolveAndValidateHost,
and have the test swap that atomically instead of net.DefaultResolver. Reads
and the test's swaps are now both atomic, and net.DefaultResolver is never
written, so the race class is eliminated by construction. Verified by running
the two tests together under -race -count=20.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FSa22vkkDLDTZctuKkmZ1A

…overage

Address PR review feedback:

- Document that a per-call variadic *fasthttp.Client is guarded only on first
  use (hosts it already dialed keep a cached, pre-guard HostClient), and that
  a full guarantee needs WithClient or a dedicated client before first use.
  Added to both the Do SSRF note and the SecurityPolicy.AllowPrivateIPs doc,
  which previously overstated the guarantee for custom clients.
- Add unit tests covering the previously-uncovered guard branches flagged by
  codecov: compose-hook error propagation, malformed dial address, the
  dual-stack delegate path, and the DialFuncWithTimeout delegate + validated
  paths. ensureClientGuarded/guardedDial/installHostClientGuard/
  newGuardedClientDialerWithTimeout are now fully covered.

No behavior change; golangci-lint clean and go test -race passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FSa22vkkDLDTZctuKkmZ1A